24 July, 2021

Background

Documentation

  • code (R, python, java, c++ etc)
  • reports, manuscripts, theses (pdf, docx, html etc)

    How do we keep these in sync?

Markdown

---
title: Example markdown
author: D. Author
date: 16-06-2020
---

This is the title
=====================

## Section 1

A paragraph of text containing a word that is **emphasised** or ~~strikethrough~~.
Followed by an unordered list: 

- item 1
- item 2

Or perhaps an enumerated list:

1. item 1
2. item 2

### Subsection 1.1

There might be a [link](https://www.markdownguide.org/) or even a table:

+-----------+---------+-----------------------+
| Item      | Example | Description           |
+===========+=========+=======================+
| numeric   | 12.34   | floating point number |
+-----------+---------+-----------------------+
| character | 'Site'  | words                 |
+-----------+---------+-----------------------+
| ...       |         |                       |
+-----------+---------+-----------------------+

Pandoc

Markdown - pandoc

---
title: Example markdown
author: D. Author
date: 16-06-2020
---

This is the title
=====================

## Section 1

A paragraph of text containing a word that is **emphasised** or ~~strikethrough~~.
Followed by an unordered list: 

- item 1
- item 2

Or perhaps an enumerated list:

1. item 1
2. item 2

### Subsection 1.1

There might be a [link](https://www.markdownguide.org/) or even a table:

+-----------+---------+-----------------------+
| Item      | Example | Description           |
+===========+=========+=======================+
| numeric   | 12.34   | floating point number |
+-----------+---------+-----------------------+
| character | 'Site'  | words                 |
+-----------+---------+-----------------------+
| ...       |         |                       |
+-----------+---------+-----------------------+

pdf

Markdown - pandoc

---
title: Example markdown
author: D. Author
date: 16-06-2020
---

This is the title
=====================

## Section 1

A paragraph of text containing a word that is **emphasised** or ~~strikethrough~~.
Followed by an unordered list: 

- item 1
- item 2

Or perhaps an enumerated list:

1. item 1
2. item 2

### Subsection 1.1

There might be a [link](https://www.markdownguide.org/) or even a table:

+-----------+---------+-----------------------+
| Item      | Example | Description           |
+===========+=========+=======================+
| numeric   | 12.34   | floating point number |
+-----------+---------+-----------------------+
| character | 'Site'  | words                 |
+-----------+---------+-----------------------+
| ...       |         |                       |
+-----------+---------+-----------------------+

html

Markdown - pandoc

---
title: Example markdown
author: D. Author
date: 16-06-2020
---

This is the title
=====================

## Section 1

A paragraph of text containing a word that is **emphasised** or ~~strikethrough~~.
Followed by an unordered list: 

- item 1
- item 2

Or perhaps an enumerated list:

1. item 1
2. item 2

### Subsection 1.1

There might be a [link](https://www.markdownguide.org/) or even a table:

+-----------+---------+-----------------------+
| Item      | Example | Description           |
+===========+=========+=======================+
| numeric   | 12.34   | floating point number |
+-----------+---------+-----------------------+
| character | 'Site'  | words                 |
+-----------+---------+-----------------------+
| ...       |         |                       |
+-----------+---------+-----------------------+

docx

Markdown - pandoc

Rmarkdown

---
title: Example markdown
author: D. Author
date: 16-06-2020
---

# This is the title

```{r summary, eval=TRUE, results='markup'}
x <- rnorm(10)
summary(x)
`` `

Rmarkdown - knitr

rmarkdown::render('file.Rmd', output_format='html_document')


Rmarkdown templates

plos

pnas

elsevier

Pracical Rmarkdown

Chunks

`` `{r readData, eval=TRUE}
mydata <- read.csv('data/myData.csv')
`` `

A chunk should represent a unit of work

  • read in data
  • perform a single set of processing
  • explore a single exploratory analysis
  • perform a analysis
  • validate model
  • summarise model
  • etc

Pracical Rmarkdown

Standalone

---
title: 'Example analysis'
author: D. Author
date: 24-07-2021
---

Load the necessary packages.
`` `{r loadLibraries, eval=TRUE}
library(tidyverse)
`` `

Read in my data
`` `{r readData, eval=TRUE}
mydata <- read.csv('data/myData.csv')
`` `

Process the data:

- create a log-transformed version of `Var`

`` `{r processData, eval=TRUE}
mydata <- myData %>% mutate(lVar = log(Var))
`` `

Pracical Rmarkdown

From external R script

---
title: 'Example analysis'
author: D. Author
date: 24-07-2021
---

`` `{r, eval=TRUE}
knitr::read_chunk('script.R')
`` `

Load the necessary packages.
`` `{r loadLibraries, eval=TRUE}
`` `

Read in my data
`` `{r readData, eval=TRUE}
`` `

Process the data:

- create a log-transformed version of `Var`

`` `{r processData, eval=TRUE}
`` `